.TH std::recursive_timed_mutex::try_lock_for 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::recursive_timed_mutex::try_lock_for \- std::recursive_timed_mutex::try_lock_for

.SH Synopsis
   template< class Rep, class Period >
   bool try_lock_for( const std::chrono::duration<Rep, Period>&           \fI(since C++11)\fP
   timeout_duration );

   Tries to lock the mutex. Blocks until the specified duration timeout_duration has
   elapsed (timeout) or the lock is acquired (owns the mutex), whichever comes first.
   On successful lock acquisition returns true, otherwise returns false.

   If timeout_duration is less or equal timeout_duration.zero(), the function behaves
   like try_lock().

   This function may block for longer than timeout_duration due to scheduling or
   resource contention delays.

   The standard recommends that a std::steady_clock is used to measure the duration. If
   an implementation uses a std::system_clock instead, the wait time may also be
   sensitive to clock adjustments.

   As with try_lock(), this function is allowed to fail spuriously and return false
   even if the mutex was not locked by any other thread at some point during
   timeout_duration.

   Prior unlock() operation on the same mutex synchronizes-with (as defined in
   std::memory_order) this operation if it returns true.

   A thread may call try_lock_for on a recursive mutex repeatedly. Successful calls to
   try_lock_for increment the ownership count: the mutex will only be released after
   the thread makes a matching number of calls to unlock().

   The maximum number of levels of ownership is unspecified. A call to try_lock_for
   will return false if this number is exceeded.

.SH Parameters

   timeout_duration - minimum duration to block for

.SH Return value

   true if the lock was acquired successfully, otherwise false.

.SH Exceptions

   Any exception thrown by timeout_duration (durations provided by the standard library
   never throw).

.SH Example


// Run this code

 #include <chrono>
 #include <iostream>
 #include <mutex>
 #include <sstream>
 #include <thread>
 #include <vector>

 using namespace std::chrono_literals;

 std::mutex cout_mutex; // control access to std::cout
 std::timed_mutex mutex;

 void job(int id)
 {
     std::ostringstream stream;

     for (int i = 0; i < 3; ++i)
     {
         if (mutex.try_lock_for(100ms))
         {
             stream << "success ";
             std::this_thread::sleep_for(100ms);
             mutex.unlock();
         }
         else
             stream << "failed ";

         std::this_thread::sleep_for(100ms);
     }

     std::lock_guard<std::mutex> lock{cout_mutex};
     std::cout << '[' << id << "] " << stream.str() << '\\n';
 }

 int main()
 {
     std::vector<std::thread> threads;
     for (int i{0}; i < 4; ++i)
         threads.emplace_back(job, i);

     for (auto& th : threads)
         th.join();
 }

.SH Possible output:

 [0] failed failed failed
 [3] failed failed success
 [2] failed success failed
 [1] success failed success

  Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to   Behavior as published            Correct behavior
   LWG 2093 C++11      try_lock_for threw nothing throws timeout-related exceptions

.SH See also

   lock           locks the mutex, blocks if the mutex is not available
                  \fI(public member function)\fP
   try_lock       tries to lock the mutex, returns if the mutex is not available
                  \fI(public member function)\fP
                  tries to lock the mutex, returns if the mutex has been
   try_lock_until unavailable until specified time point has been reached
                  \fI(public member function)\fP
   unlock         unlocks the mutex
                  \fI(public member function)\fP
